
/**
 * @ProjectName: 
 * @Copyright: 2014 lisheng  All Right Reserved.
 * @address: toughheart@163.com
 * @date: 2016年1月12日 下午9:29:29
 * @Description: 本内容未经本人允许禁止使用、转发.
 */
 
package com.ls.fw.auth.oauth2.as.handler;

import org.apache.oltu.oauth2.as.issuer.OAuthIssuer;
import org.apache.oltu.oauth2.as.request.OAuthAuthzRequest;
import org.apache.oltu.oauth2.as.request.OAuthTokenRequest;
import org.apache.oltu.oauth2.common.exception.OAuthSystemException;

import com.ls.fw.auth.oauth2.as.exception.OAuth2Exception;
import com.ls.fw.auth.oauth2.as.service.OAuthService;


/**
 * OAuth 2.0定义了四种授权方式。
    授权码模式（authorization code）
    简化模式（implicit）
    密码模式（resource owner password credentials）
    客户端模式（client credentials）
 * @author lisheng
 * @date 2016年1月12日 下午9:29:29
 * @version V1.0 
 */
public interface OAuth2Handler {

	
	/**
	 * 
	 * @author lisheng
	 * @date 2016年1月12日 下午9:31:41
	 * @version V1.0
	 * @return
	 */
	OAuthService getOauthService();

	
	/**
	 * 获取code
	 * 授权码模式（authorization code）是功能最完整、流程最严密的授权模式。
	 * 它的特点就是通过客户端的后台服务器，与"服务提供商"的认证服务器进行互动。
	 * 步骤：
	 *  （A）用户访问客户端，后者将前者导向认证服务器。
		（B）用户选择是否给予客户端授权。
		（C）假设用户给予授权，认证服务器将用户导向客户端事先指定的"重定向URI"（redirection URI），同时附上一个授权码。
		（D）客户端收到授权码，附上早先的"重定向URI"，向认证服务器申请令牌。这一步是在客户端的后台的服务器上完成的，对用户不可见。
		（E）认证服务器核对了授权码和重定向URI，确认无误后，向客户端发送访问令牌（access token）和更新令牌（refresh token）。
	 * A步骤参数：
	 *  response_type：表示授权类型，必选项，此处的值固定为"code"
		client_id：表示客户端的ID，必选项
		redirect_uri：表示重定向URI，可选项
		scope：表示申请的权限范围，可选项
		state：表示客户端的当前状态，可以指定任意值，认证服务器会原封不动地返回这个值。
	 * @author lisheng
	 * @date 2016年1月12日 下午9:55:39
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception
	 * @throws OAuthSystemException
	 */
	String getAuthCode(OAuthAuthzRequest oauthRequest) throws OAuth2Exception,
			OAuthSystemException;


	
	/**
	 * 通过授权码code获取token
	 * @author lisheng
	 * @date 2016年1月13日 下午8:49:27
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception 
	 * @throws OAuthSystemException 
	 */
	String getAccessTokenByCode(OAuthTokenRequest oauthRequest) throws OAuth2Exception, OAuthSystemException;


	
	/**
	 * 通过refreshToken获取token
	 * @author lisheng
	 * @date 2016年1月13日 下午9:46:37
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception
	 * @throws OAuthSystemException
	 */
	String getAccessTokenByRefreshToken(OAuthTokenRequest oauthRequest)
			throws OAuth2Exception, OAuthSystemException;


	
	/**
	 * 通过授权码code获取refreshToken
	 * @author lisheng
	 * @date 2016年1月13日 下午9:51:13
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception
	 * @throws OAuthSystemException
	 */
	String getRefreshTokenByCode(OAuthTokenRequest oauthRequest)
			throws OAuth2Exception, OAuthSystemException;


	
	/**
	 * 简化模式（implicit grant type）不通过第三方应用程序的服务器，
	 * 直接在浏览器中向认证服务器申请令牌，跳过了"授权码"这个步骤，
	 * 因此得名。所有步骤在浏览器中完成，令牌对访问者是可见的，
	 * 且客户端不需要认证。
	 * 步骤：
	 * （A）客户端将用户导向认证服务器。
		（B）用户决定是否给于客户端授权。
		（C）假设用户给予授权，认证服务器将用户导向客户端指定的"重定向URI"，并在URI的Hash部分包含了访问令牌。
		（D）浏览器向资源服务器发出请求，其中不包括上一步收到的Hash值。
		（E）资源服务器返回一个网页，其中包含的代码可以获取Hash值中的令牌。
		（F）浏览器执行上一步获得的脚本，提取出令牌。
 		（G）浏览器将令牌发给客户端。
	 * @author lisheng
	 * @date 2016年1月14日 下午8:19:34
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuthSystemException
	 */
	String getAccessToken(OAuthAuthzRequest oauthRequest)
			throws OAuthSystemException;


	
	/**
	 * 
	 * @author lisheng
	 * @date 2016年1月14日 下午8:48:50
	 * @version V1.0
	 * @return
	 */
	OAuthIssuer getOauthIssuer();


	
	/**
	 * 
	 * @author lisheng
	 * @date 2016年1月14日 下午8:51:21
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception
	 * @throws OAuthSystemException
	 */
	String getRefreshToken(OAuthTokenRequest oauthRequest)
			throws OAuth2Exception, OAuthSystemException;


	/**
	 * 
	 * @author lisheng
	 * @date 2016年1月14日 下午9:16:52
	 * @version V1.0
	 * @param oauthRequest
	 * @return
	 * @throws OAuth2Exception
	 * @throws OAuthSystemException
	 */
	String getRefreshTokenByRefreshToken(OAuthTokenRequest oauthRequest)
			throws OAuth2Exception, OAuthSystemException;

}
